Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NXSoundParameters

Adopted By:	NXSoundParameters (the class)
NXSoundDevice

Declared In:	soundkit/NXSoundParameters.h

Protocol Description

The NXSoundParameters protocol defines methods that set and retrieve the values of particular sound attribute, or ªparametersº.  Each parameter is identified by an integer constant called a parameter key.  Parameters always take numeric values; some of these values are represented by integer constants called parameter values.  Cumulatively, the constants that represent parameter keys and parameter values are called parameter tags; the list of parameter tags, divided into keys and values, that are defined by the Sound Kit is given in the section ªTypes and Constants.º  (To avoid confusion, the parameter tags that represent parameter values are referred to as parameter value tags.)

Hardware and Software Parameters

A parameter key corresponds either to a hardware or a software sound attribute.  Hardware parameter keys take the form ªNX_SoundDeviceAttributeº; for example, NX_SoundDeviceMuteSpeaker.  Software parameter keys take the form ªNX_SoundStreamAttributeº, as in NX_SoundStreamGainStereo.

Software parameter keys are guaranteed to be applicable to any computer.  A similar assurance can't be made for the hardware parameter keys.  For example, the NX_SoundDeviceMuteSpeaker parameter key only makes sense for computers that have a built-in speaker.  The getParameters:count: is useful in determining which parameter keys are used on a particular hardware platform, as explained in the method descriptions below.

Parameter Values

To set a parameter's value, you use one of the setParameter:toType: methods, passing a parameter key as the first argument, and a value of type Type as the second.  Parameters only accept numeric values; the value-setting methods that are defined here let you set a parameter as an int, a float, or a BOOL.  

 Some parameters take discrete values that are represented by parameter value tags.  For example, the NX_SoundDeviceAnalogInput parameter key accepts two values, NX_SoundDeviceAnalogInputSource_Microphone and NX_SoundDeviceAnalogInputSource_LineIn.  The list of parameters keys that take parameter value tags is given below:

	NX_SoundDeviceAnlogInputSource
		NX_SoundDeviceAnalogInputSource_Microphone
		NX_SoundDeviceAnalogInputSource_LineIn

	NX_SoundStreamDataEncoding
		NX_SoundStreamDataEncoding_Linear16
    		NX_SoundStreamDataEncoding_Linear8
		NX_SoundStreamDataEncoding_Mulaw8
		NX_SoundStreamDataEncoding_Alaw8
		NX_SoundStreamDataEncoding_AES

	NX_SoundStreamSource
		NX_SoundStreamSource_Analog
		NX_SoundStreamSource_AES

    	NX_SoundStreamSink
		NX_SoundStreamSink_Analog
		NX_SoundStreamSink_AES

The getValues:count:forParameter: method returns the parameter value tags for the given (last argument) parameter key.  Since not all parameter keys take parameter value tags, this method isn't meaningful for all parameter key arguments.  

Applying NXSoundParameters Objects

A single NXSoundParameters object can hold key/value pairs for any number of parameters.  You can apply these settings to an NXSoundDevice or NXSoundStream object through methods defined in those classes.  The object takes and applies the parameters that are meaningful to it; in other words, NXSoundDevice objects set hardware parameters, NXSoundStream objects set software parameters.

The Sound Kit provides the NXSoundParameters class as a convenient cover for this protocol.  Instances of the class implement the methods found here so you can encapsulate and ªpass aroundº your favorite sound parameter settings.  

In addition, the NXSoundDevice class conforms to the protocol, allowing you to set hardware parameters directly in an NXSoundDevice object.  When you create an NXSoundDevice object, the parameter keys that represent the supported (hardware) parameters are automatically set to default values. 

Method Types

Getting parameter values	- boolValueForParameter:
- floatValueForParameter:
- intValueForParameter:

Setting parameter values	- setParameter:toBool:
- setParameter:toFloat:
- setParameter:toInt:

Querying parameters	- getParameters:count:
- getValues:count:forParameter:
- isParameterPresent:
- removeParameter:

Instance Methods

boolValueForParameter:

- (BOOL)boolValueForParameter:(NXSoundParameterTag)tag 

Returns the value of the parameter represented by tag as a boolean, converting the value if necessary.

floatValueForParameter:

- (float)floatValueForParameter:(NXSoundParameterTag)tag 

Returns the value of the parameter represented by tag as a float, converting the value if necessary.

getParameters:count:

- (void)getParameters:(const NXSoundParameterTag **)tagList 
count:(unsigned int *)tagCount 

Returns, in tagList, an array of the parameter keys that are present in the NXSoundParameters object.  The number of elements in the list is returned in count.  Note that if the receiver is a newly-initialized NXSoundDevice object, then the keys in the list represent the hardware parameters that are supported by the hardware.

getValues:count:forParameter:

- (void)getValues:(const NXSoundParameterTag **)valueTagList 
count:(unsigned int *)numValues 
forParameter:(NXSoundParameterTag)tag 

Returns, in valueTagList, a list of the parameter values tags that are accepted by the parameter key tag tag.   If the parameter key doesn't accept parameter value tags, then the list will be empty.

intValueForParameter:

- (int)intValueForParameter:(NXSoundParameterTag)ptag 

Returns the value of the parameter represented by tag as an int, converting the value if necessary.

isParameterPresent:

- (BOOL)isParameterPresent:(NXSoundParameterTag)tag 

Returns YES if the parameter represented by tag is present (has been set) in the object.

removeParameter:

- (void)removeParameter:(NXSoundParameterTag)tag 

Removes the parameter represented by tag from the object.

setParameter:toBool:

- (void)setParameter:(NXSoundParameterTag)tag toBool:(BOOL)flag 

Sets the parameter represented by tag to the boolean value given by flag.

setParameter:toFloat:

- (void)setParameter:(NXSoundParameterTag)ptag toFloat:(float)aFloat 

Sets the parameter represented by tag to the floating-point value given by aFloat.

setParameter:toInt:

- (void)setParameter:(NXSoundParameterTag)tag toInt:(int)anInt 

Sets the parameter represented by tag to the integer value given by anInt.